<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
<!-- qtquick-modules-with-plugins.qdoc -->
  <title>Using QML Modules with Plugins | Qt Creator Manual</title>
  <link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
  <script type="text/javascript">
    document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
    // loading style sheet breaks anchors that were jumped to before
    // so force jumping to anchor again
    setTimeout(function() {
        var anchor = location.hash;
        // need to jump to different anchor first (e.g. none)
        location.hash = "#";
        setTimeout(function() {
            location.hash = anchor;
        }, 0);
    }, 0);
  </script>
</head>
<body>
<div class="header" id="qtdocheader">
  <div class="main">
    <div class="main-rounded">
      <div class="navigationbar">
        <table><tr>
<td ><a href="index.html">Qt Creator Manual</a></td><td >Using QML Modules with Plugins</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="index.html">Qt Creator Manual 4.11.1</a></td>
        </tr></table>
      </div>
    </div>
<div class="content">
<div class="line">
<div class="content mainContent">
  <link rel="prev" href="creator-quick-ui-forms.html" />
  <link rel="next" href="quick-converting-ui-projects.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="creator-quick-ui-forms.html">Qt Quick UI Forms</a>
<span class="naviSeparator">  &#9702;  </span>
<a class="nextPage" href="quick-converting-ui-projects.html">Converting UI Projects to Applications</a>
</p><p/>
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#registering-qml-types">Registering QML Types</a></li>
<li class="level1"><a href="#generating-qmltypes-files">Generating qmltypes Files</a></li>
<li class="level2"><a href="#dumping-plugins-automatically">Dumping Plugins Automatically</a></li>
<li class="level1"><a href="#importing-qml-modules">Importing QML Modules</a></li>
<li class="level1"><a href="#running-qml-modules-in-design-mode">Running QML Modules in Design Mode</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Using QML Modules with Plugins</h1>
<span class="subtitle"></span>
<!-- $$$creator-qml-modules-with-plugins.html-description -->
<div class="descr"> <a name="details"></a>
<p>QML modules may use plugins to expose components defined in C++ to QML applications. Qt Creator cannot load the plugins to determine the details of the contained components, and therefore, the modules must provide extra type information for code completion and the semantic checks to work correctly.</p>
<p>To create a QML module and make it appear in the <b>Library</b> in the Design mode:</p>
<ol class="1" type="1"><li>Create custom QML controls and place all the <code>.qml</code> files in a directory dedicated to your module.</li>
<li>Create a <code>qmldir</code> file for your module and place it in the module directory. For more information, see <a href="http://doc.qt.io/qt-5/qtqml-modules-qmldir.html">Module Definition qmldir Files</a>.</li>
<li>Create a <code>qmltypes</code> file, preferably using <code>qmlplugindump</code>. For more information see, <a href="creator-qml-modules-with-plugins.html#generating-qmltypes-files">Generating qmltypes Files</a>.</li>
<li>Create a directory named <code>designer</code> in your module directory.</li>
<li>Create a <code>.metainfo</code> file for your module and place it in the <code>designer</code> directory. Meta information is needed to display the components in the <b>QML Types</b> tab in the <b>Library</b>. Use a metainfo file delivered with Qt, such as <code>qtquickcontrols2.metainfo</code>, as an example.</li>
<li>Import your module into a project using <code>QML_IMPORT_PATH</code> in the .pro file: <code>QML_IMPORT_PATH += path/to/module</code>. For more information, see <a href="creator-qml-modules-with-plugins.html#importing-qml-modules">Importing QML Modules</a>.</li>
<li>Make sure that the QML emulation layer used in the Design mode is built with the same Qt version as your QML modules. For more information, see <a href="creator-qml-modules-with-plugins.html#running-qml-modules-in-design-mode">Running QML Modules in Design Mode</a>. You can also try skipping this step and take it later, if necessary.</li>
</ol>
<p>Your module should now appear in the <b>Imports</b> tab in the <b>Library</b> in the Design mode. Your components should appear in the <b>QML Types</b> tab if a valid <code>.metainfo</code> file is in place.</p>
<a name="registering-qml-types"></a>
<h2 id="registering-qml-types">Registering QML Types</h2>
<p>When you write a QML module or use QML from a C++ application, you typically register new types with the qmlRegisterType() function or expose some class instances with <a href="http://doc.qt.io/qt-5/qqmlcontext.html#setContextProperty">QQmlContext::setContextProperty</a>(). The Qt Creator C++ code model now scans for these calls and tells the QML code model about them. This means that properties are displayed during code completion and the JavaScript code checker does not complain about unknown types. However, this works only when the source code is available, and therefore, you must explicitly generate type information for QML modules with plugins before distributing them.</p>
<p>Classes registered with <code>qmlRegisterType()</code> can be used as backend objects in the Design mode. For more information, see <a href="qmldesigner-connections.html">Adding Connections</a>.</p>
<a name="generating-qmltypes-files"></a>
<h2 id="generating-qmltypes-files">Generating qmltypes Files</h2>
<p>Ideally, QML modules have a <code>plugins.qmltypes</code> file in the same directory as the <code>qmldir</code> file. The <code>qmltypes</code> file contains a description of the types exported by the module's plugins and is loaded by Qt Creator when the module is imported.</p>
<p>For Qt 4.8 and later, one or more <code>qmltypes</code> files can be listed in the <code>qmldir</code> file under the <code>typeinfo</code> header. These files will be read in addition to <code>plugins.qmltypes</code>. For more information, see <a href="http://doc.qt.io/qt-5/qtqml-modules-qmldir.html#writing-a-qmltypes-file">Writing a qmltypes File</a>.</p>
<p>You can create and edit <code>qmltypes</code> files manually, but you are recommended to use the <code>qmlplugindump</code> tool shipped with Qt 4.8 and later to generate them automatically.</p>
<p>Once you have obtained <code>qmlplugindump</code> for the Qt version the QML module's plugins were compiled with, run the following command to load My.Module version 1.0 from <code>/import/path/my/module</code> including all its plugins and output a description of the plugins' types to <code>/import/path/my/module/plugins.qmltypes</code>:</p>
<pre class="cpp">

  qmlplugindump <span class="operator">-</span>nonrelocatable My<span class="operator">.</span>Module <span class="number">1.0</span> <span class="operator">/</span>import<span class="operator">/</span>path <span class="operator">&gt;</span> <span class="operator">/</span>import<span class="operator">/</span>path<span class="operator">/</span>my<span class="operator">/</span>module<span class="operator">/</span>plugins<span class="operator">.</span>qmltypes

</pre>
<p>You can safely ignore the debug output.</p>
<p>For Qt 4.7&#x2e;x, you can compile a version of the tool called <code>qmldump</code> from the sources in <code>&lt;QtCreator&gt;/share/qtcreator/qml/qmldump</code> if the Qt version contains private headers.</p>
<a name="dumping-plugins-automatically"></a>
<h3 id="dumping-plugins-automatically">Dumping Plugins Automatically</h3>
<p>If a module with plugins lacks the <code>qmltypes</code> file, Qt Creator tries to generate a temporary file itself by running the <code>qmldump</code> program in the background. However, this automatic dumping is a fallback mechanism with many points of failure and you cannot rely upon it.</p>
<a name="importing-qml-modules"></a>
<h2 id="importing-qml-modules">Importing QML Modules</h2>
<p>By default, Qt Creator will look in the QML import path of Qt for QML modules. If your applications adds additional import paths that Qt Creator should use, then you can specify those using <code>QML_IMPORT_PATH</code> in the <code>.pro</code> file of your application.</p>
<p>If you use CMake, add the following command to the CMakeLists.txt file to set the QML import path:</p>
<pre class="cpp">

  set(QML_IMPORT_PATH ${CMAKE_SOURCE_DIR}<span class="operator">/</span>qml ${CMAKE_BINARY_DIR}<span class="operator">/</span>imports CACHE STRING <span class="string">&quot;&quot;</span> FORCE)

</pre>
<p>The import path affects all the targets built by the CMake project.</p>
<a name="running-qml-modules-in-design-mode"></a>
<h2 id="running-qml-modules-in-design-mode">Running QML Modules in Design Mode</h2>
<p>A QML emulation layer (also called QML Puppet) is used in the Design mode to render and preview images and to collect data. To be able to render custom types correctly from QML modules, the emulation layer must be built with the same Qt version as the QML modules.</p>
<p>By default, a fallback emulation layer is provided by Qt Creator and built with the same Qt version as Qt Creator. Therefore, your QML modules will mostly not work out of the box.</p>
<p>To use an emulation layer that is built with the Qt configured in the build and run kit for the project, select <b>Tools</b> &gt; <b>Options</b> &gt; <b>Qt Quick</b> &gt; <b>Qt Quick Designer</b> &gt; <b>Use QML emulation layer which is built by the selected Qt</b> radio button. Qt Creator builds the emulation layer when you select the Design mode.</p>
<p>A plugin should behave differently depending on whether it is run by the emulation layer or an application. For example, animations should not be run in the Design mode. You can use the value of the QML_PUPPET_MODE environment variable to check whether the plugin is currently being run by an application or edited in the Design mode.</p>
<p>If you want to use a different module in the Design mode than in your actual application for example to mockup C++ items, then you can use <code>QML_DESIGNER_IMPORT_PATH</code> in the <code>.pro</code> file (for qmake projects), or declare and set the property qmlDesignerImportPaths in your product (for Qbs projects). Modules in the import paths defined in <code>QML_DESIGNER_IMPORT_PATH</code> will be used only in the Design mode. For an example, see <a href="http://doc.qt.io/qt-5/qtquickcontrols-contactlist-example.html">Qt Quick Controls - Contact List</a>.</p>
</div>
<!-- @@@creator-qml-modules-with-plugins.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="creator-quick-ui-forms.html">Qt Quick UI Forms</a>
<span class="naviSeparator">  &#9702;  </span>
<a class="nextPage" href="quick-converting-ui-projects.html">Converting UI Projects to Applications</a>
</p>
        </div>
       </div>
   </div>
   </div>
</div>
<div class="footer">
   <p>
   <acronym title="Copyright">&copy;</acronym> 2019 The Qt Company Ltd.
   Documentation contributions included herein are the copyrights of
   their respective owners.<br>    The documentation provided herein is licensed under the terms of the    <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation    License version 1.3</a> as published by the Free Software Foundation.<br>    Qt and respective logos are trademarks of The Qt Company Ltd.     in Finland and/or other countries worldwide. All other trademarks are property
   of their respective owners. </p>
</div>
</body>
</html>
